home *** CD-ROM | disk | FTP | other *** search
/ Almathera Ten Pack 3: CDPD 3 / Almathera Ten on Ten - Disc 3: CDPD3.iso / ab20 / unarced / graphics / augjpeg / readme < prev    next >
Text File  |  1995-03-17  |  10KB  |  224 lines
  1. README   15-Aug-91
  2. ==================
  3.  
  4. This distribution contains the fourth draft of the free JPEG working group's
  5. results.  The copyright status of this code has not yet been decided, but in
  6. any case we intend to make it freely usable by all comers, for either
  7. commercial or non-commercial purposes.  You may incorporate derivatives of
  8. this code into proprietary products, so long as you do not attempt to stop
  9. other people from using the original code (by copyrighting it yourself, for
  10. example).
  11.  
  12. This code is the work of Tom Lane, Philip Gladstone, Luis Ortiz, and other
  13. members of the free JPEG working group.
  14.  
  15. THIS CODE IS NOT COMPLETE NOR DEBUGGED.  It is not guaranteed to be useful for
  16. anything, nor to be compatible with subsequent releases.
  17.  
  18. Please report problems to tgl@cs.cmu.edu.
  19.  
  20.  
  21. WHAT'S HERE
  22. ===========
  23.  
  24. This distribution contains a skeleton system based on the "architecture"
  25. document I sent out a while ago (the latest draft of which is included).
  26. The intermodule interfaces are fully fleshed out, but many of the modules
  27. are just stubs or minimal implementations.  The code does compile and it can
  28. compress or decompress JPEG files into raw-format PPM or PGM files.
  29.  
  30. This software can be used on several levels:
  31.  
  32. * As canned software for PPM<=>JPEG conversion.  Just edit the Makefile and
  33.   configuration files as needed (see SETUP), compile and go.  Members of the
  34.   JPEG group will improve the out-of-the-box functionality as time goes on.
  35.  
  36. * As the basis for other JPEG programs.  For example, you could incorporate
  37.   the decompressor into a general image viewing package by replacing the
  38.   output module with write-to-screen functions.  For an implementation on
  39.   specific hardware, you might want to replace some of the inner loops with
  40.   assembly code.  For a non-command-line-driven system, you might want a
  41.   different user interface.  (Members of the group will be producing Macintosh
  42.   and Amiga versions with appropriate user interfaces, for example.)
  43.  
  44. * As a toolkit for experimentation with JPEG and JPEG-like algorithms.  Most
  45.   of the individual decisions you might want to mess with are packaged up into
  46.   separate modules.  For example, the details of color-space conversion and
  47.   subsampling techniques are each localized in one compressor and one
  48.   decompressor module.  You'd probably also want to revise the user interface
  49.   to give you more detailed control over the JPEG compression parameters.
  50.  
  51.  
  52. SETUP
  53. =====
  54.  
  55. First, select a makefile and copy it to "Makefile".  "makefile.unix"
  56. is appropriate for most Unix and Unix-like systems.  Special makefiles are
  57. included for various PC compilers.
  58.  
  59. Look over the makefile and adjust options as needed.  In particular, you'll
  60. need to change the CC= and CFLAGS= definitions if you don't have gcc.  If you
  61. have a function-prototype-less compiler, be sure to uncomment the .c.o rule
  62. and say "make ansi2knr".  (Thanks to Peter Deutsch for ansi2knr.)
  63.  
  64. Also look over jconfig.h and adjust #defines as necessary.  If you have an
  65. ANSI-compilant C compiler (gcc for instance), no changes should be necessary
  66. except for RIGHT_SHIFT_IS_UNSIGNED.  For older compilers other mods may be
  67. needed depending on what ANSI features are supported.
  68.  
  69. Then say "make".
  70.  
  71. If you have trouble with missing system include files or inclusion of the
  72. wrong ones, you can fix it in jinclude.h.
  73.  
  74. Note you DON'T need the PBMPLUS library to compile; for the moment I made
  75. hard-wired PPM read/write routines (sorry 'bout that, Jef).  However, you'll
  76. need the PBMPLUS program suite in order to accomplish much of anything useful,
  77. since only PPM/PGM-format image files are currently supported.
  78.  
  79. As a quick test of functionality I've included three sample files.
  80.     testorig.jpg    same as blkint.jpg from JPEG validation floppy.
  81.     testimg.ppm    output of djpeg testorig.jpg
  82.     testimg.jpg    output of cjpeg testimg.ppm
  83. The two .jpg files aren't identical due to different parameter choices (and
  84. wouldn't be anyway, since JPEG is lossy).  However, if you can generate
  85. duplicates of testimg.ppm and testimg.jpg then you probably have a working
  86. port.  "make test" will perform the necessary comparisons (by generating
  87. testout.ppm and testout.jpg and comparing these to testimg.*).
  88.  
  89. If you need to make a smaller version of the JPEG software, some optional
  90. functions can be removed at compile time.  See the xxx_SUPPORTED #defines
  91. in jconfig.h.  (Not a lot is actually removed right now, but as more optional
  92. stuff gets added, this mechanism will start to make a difference.)
  93.  
  94.  
  95. USAGE
  96. =====
  97.  
  98. The user interface is pretty minimal at this point.  I haven't bothered to
  99. generate man pages since the options need reconsideration anyhow.  At the
  100. moment, things work like this:
  101.  
  102. To compress:    cjpeg [options] [file.ppm] >file.jpg
  103.  
  104. To decompress:    djpeg [options] [file.jpg] >file.ppm
  105.  
  106. The programs read the specified input file, or standard input if none is
  107. named.  They always write to standard output (with trace/error messages to
  108. standard error).  The non-JPEG file format is raw-format PPM, or PGM for
  109. monochrome images.
  110.  
  111. The command line options for cjpeg are:
  112.  
  113.     -I        Generate noninterleaved file (not yet supported).
  114.     -Q quality    Scale quantization tables to adjust quality.
  115.             Quality is 0 (worst) to 100 (best); default is 75.
  116.     -a        Use arithmetic coding rather than Huffman coding.
  117.             (Not currently supported, see LEGAL ISSUES.)
  118.     -o        Perform optimization of entropy encoding parameters.
  119.             Without this, default Huffman or arithmetic
  120.             parameters are used.  -o makes the JPEG file a tad
  121.             smaller, but compression uses much more memory.
  122.             Image quality is unaffected by -o.
  123.     -d        Enable debug printout.  More -d's give more printout.
  124.  
  125. -Q 100 will generate a quantization table of all 1's, meaning no quantization
  126. loss; then any differences between input and output images are due to roundoff
  127. error in the DCT or colorspace-conversion steps.  Try -Q 2 (or so) for some
  128. nice Cubist effects.  (Note that -Q values below about 25 generate 2-byte
  129. quantization tables, which are not decodable by pure baseline JPEG decoders.
  130. cjpeg emits a warning message when you give such a -Q value.)
  131.  
  132. The command line options for djpeg are:
  133.  
  134.     -b        Perform cross-block smoothing.  This is quite
  135.             memory-intensive & doesn't seem to help a lot
  136.             (I'm not convinced we've implemented it correctly).
  137.     -q n        Quantize to n colors.
  138.     -D        Use Floyd-Steinberg dithering in color quantization.
  139.     -2        Use two-pass color quantization (not yet supported).
  140.     -d        Enable debug printout.  More -d's give more printout.
  141.  
  142. Color quantization currently uses a rather shoddy algorithm (although it's not
  143. too bad when dithered).  You can get better results by applying ppmquant to
  144. the unquantized output of djpeg.
  145.  
  146. Note that djpeg *can* read noninterleaved files even though cjpeg can't yet
  147. generate them.
  148.  
  149.  
  150. REFERENCES
  151. ==========
  152.  
  153. The best and most readily available introduction to the JPEG compression
  154. algorithm is Wallace's article in the April '91 CACM:
  155.     Wallace, Gregory K.  "The JPEG Still Picture Compression Standard",
  156.     Communications of the ACM, April 1991 (v. 34 no. 4), pp. 30-44.
  157. (Adjacent articles in that issue discuss MPEG motion picture compression,
  158. applications of JPEG, and related topics.)  I highly recommend reading that
  159. article before looking at any of the JPEG code.
  160.  
  161. For more detail about the JPEG standard you pretty much have to go to the
  162. draft standard, which is not nearly as intelligible as Wallace's article.
  163. The current version is ISO/IEC Committee Draft CD 10918-1 dated 1991-03-15.
  164.  
  165.  
  166. SUPPORTING SOFTWARE
  167. ===================
  168.  
  169. You will probably want Jef Poskanzer's PBMPLUS image software; this provides
  170. many useful operations on PPM-format image files.  In particular, it can
  171. convert PPM images to and from a wide range of other formats.  You can FTP
  172. this free software from export.lcs.mit.edu (contrib/pbmplus.tar.Z) or
  173. ftp.ee.lbl.gov (pbmplus.tar.Z).
  174.  
  175. If you are using X Windows you might want to use the xv or xloadimage viewers
  176. to save yourself the trouble of converting PPM to some other format.
  177. I believe both of these can be found in the contrib directory at
  178. export.lcs.mit.edu.
  179.  
  180.  
  181. LEGAL ISSUES
  182. ============
  183.  
  184. It appears that the arithmetic coding option of the JPEG spec is covered by
  185. patents held by IBM, and possibly also patents of AT&T and Mitsubishi.  Hence
  186. arithmetic coding cannot legally be used without obtaining one or more
  187. licenses.  For this reason, support for arithmetic coding has been removed
  188. from the free JPEG software.  (Since arithmetic coding provides only a
  189. marginal gain over the unpatented Huffman mode, it is unlikely that very many
  190. people will choose to use it.  If you do obtain such a license, contact me for
  191. a copy of our arithmetic coding modules.)  So far as I am aware, there are no
  192. patent or copyright restrictions on the remaining code.
  193.  
  194. It may prove necessary for the free JPEG group to copyright this software.
  195. (I have heard, for example, that copyright is required for any software to
  196. be distributed as X Windows contrib software.)  If we do that, we will not
  197. place any restrictions on the distribution, use, or modification of the code.
  198.  
  199.  
  200. TO DO
  201. =====
  202.  
  203. Obviously most of the modules need fleshing out to provide more complete
  204. implementations, or to provide faster paths for common cases.  I would suggest
  205. that we not start doing that just yet, but instead test out how portable the
  206. code is and eliminate any portability problems that have snuck into the
  207. intermodule interfaces.  That way, subsequent improvement of individual
  208. modules can proceed pretty much in isolation.
  209.  
  210. I'd appreciate it if people would compile and check out the code on as wide a
  211. variety of systems as possible, and let me know of any portability problems
  212. encountered (with solutions, if possible).  I expect I missed some places
  213. where casts were needed, and the usage of standard include files probably
  214. still has some problems.
  215.  
  216. The current code seems to be reasonably portable to MS-DOS.  The existing
  217. memory manager module (jvirtmem.c) will eventually need to be replaced with
  218. one that can swap "big" images out to temp files, but the current code doesn't
  219. ask for big images (unless you use -I, -o or -b), so that functionality isn't
  220. essential yet.
  221.  
  222.                 tom lane
  223.                 tgl@cs.cmu.edu
  224.